<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>arbitrary &mdash; The Logtalk Handbook v3.93.0-b01 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
      <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=396eccfe" />

  
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script src="../_static/jquery.js?v=5d32c60e"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
        <script src="../_static/documentation_options.js?v=c8100655"></script>
        <script src="../_static/doctools.js?v=9a2dae69"></script>
        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/js/theme.js"></script>
    <!-- begin favicon -->
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
    <link rel="manifest" href="/site.webmanifest" />
    <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#5bbad5" />
    <meta name="msapplication-TileColor" content="#355b95" />
    <meta name="theme-color" content="#ffffff" />
    <!-- end favicon -->
    
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="assignvars" href="assignvars.html" />
    <link rel="prev" title="Overview" href="overview.html" />
   
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            The Logtalk Handbook
              <img src="../_static/logtalk.gif" class="logo" alt="Logo"/>
          </a>
              <div class="version">
                3.93.0
              </div>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
    
              <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../userman/index.html">User Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../refman/index.html">Reference Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devtools/index.html">Developer Tools</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Libraries</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#"><code class="docutils literal notranslate"><span class="pre">arbitrary</span></code></a><ul>
<li class="toctree-l3"><a class="reference internal" href="#api-documentation">API documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="#loading">Loading</a></li>
<li class="toctree-l3"><a class="reference internal" href="#testing">Testing</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pre-defined-types">Pre-defined types</a></li>
<li class="toctree-l3"><a class="reference internal" href="#usage">Usage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#defining-new-generators-and-shrinkers">Defining new generators and shrinkers</a></li>
<li class="toctree-l3"><a class="reference internal" href="#scoped-generators-and-shrinkers">Scoped generators and shrinkers</a></li>
<li class="toctree-l3"><a class="reference internal" href="#reproducing-sequences-of-arbitrary-terms">Reproducing sequences of arbitrary terms</a></li>
<li class="toctree-l3"><a class="reference internal" href="#default-size-of-generated-terms">Default size of generated terms</a></li>
<li class="toctree-l3"><a class="reference internal" href="#known-issues">Known issues</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="assignvars.html"><code class="docutils literal notranslate"><span class="pre">assignvars</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="base64.html"><code class="docutils literal notranslate"><span class="pre">base64</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="basic_types.html"><code class="docutils literal notranslate"><span class="pre">basic_types</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="cbor.html"><code class="docutils literal notranslate"><span class="pre">cbor</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="core.html"><code class="docutils literal notranslate"><span class="pre">core</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="coroutining.html"><code class="docutils literal notranslate"><span class="pre">coroutining</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="csv.html"><code class="docutils literal notranslate"><span class="pre">csv</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="dates.html"><code class="docutils literal notranslate"><span class="pre">dates</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="dependents.html"><code class="docutils literal notranslate"><span class="pre">dependents</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="dictionaries.html"><code class="docutils literal notranslate"><span class="pre">dictionaries</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="dif.html"><code class="docutils literal notranslate"><span class="pre">dif</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="edcg.html"><code class="docutils literal notranslate"><span class="pre">edcg</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="events.html"><code class="docutils literal notranslate"><span class="pre">events</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="expand_library_alias_paths.html"><code class="docutils literal notranslate"><span class="pre">expand_library_alias_paths</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="expecteds.html"><code class="docutils literal notranslate"><span class="pre">expecteds</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="format.html"><code class="docutils literal notranslate"><span class="pre">format</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="genint.html"><code class="docutils literal notranslate"><span class="pre">genint</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="gensym.html"><code class="docutils literal notranslate"><span class="pre">gensym</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="git.html"><code class="docutils literal notranslate"><span class="pre">git</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="grammars.html"><code class="docutils literal notranslate"><span class="pre">grammars</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="heaps.html"><code class="docutils literal notranslate"><span class="pre">heaps</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="hierarchies.html"><code class="docutils literal notranslate"><span class="pre">hierarchies</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="hook_flows.html"><code class="docutils literal notranslate"><span class="pre">hook_flows</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="hook_objects.html"><code class="docutils literal notranslate"><span class="pre">hook_objects</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="html.html"><code class="docutils literal notranslate"><span class="pre">html</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="ids.html"><code class="docutils literal notranslate"><span class="pre">ids</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="intervals.html"><code class="docutils literal notranslate"><span class="pre">intervals</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="java.html"><code class="docutils literal notranslate"><span class="pre">java</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="json.html"><code class="docutils literal notranslate"><span class="pre">json</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="json_lines.html"><code class="docutils literal notranslate"><span class="pre">json_lines</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="listing.html"><code class="docutils literal notranslate"><span class="pre">listing</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="logging.html"><code class="docutils literal notranslate"><span class="pre">logging</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="loops.html"><code class="docutils literal notranslate"><span class="pre">loops</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="meta.html"><code class="docutils literal notranslate"><span class="pre">meta</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="meta_compiler.html"><code class="docutils literal notranslate"><span class="pre">meta_compiler</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="mutations.html"><code class="docutils literal notranslate"><span class="pre">mutations</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="nested_dictionaries.html"><code class="docutils literal notranslate"><span class="pre">nested_dictionaries</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="optionals.html"><code class="docutils literal notranslate"><span class="pre">optionals</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="options.html"><code class="docutils literal notranslate"><span class="pre">options</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="os.html"><code class="docutils literal notranslate"><span class="pre">os</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="queues.html"><code class="docutils literal notranslate"><span class="pre">queues</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="random.html"><code class="docutils literal notranslate"><span class="pre">random</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="reader.html"><code class="docutils literal notranslate"><span class="pre">reader</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="recorded_database.html"><code class="docutils literal notranslate"><span class="pre">recorded_database</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="redis.html"><code class="docutils literal notranslate"><span class="pre">redis</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="sets.html"><code class="docutils literal notranslate"><span class="pre">sets</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="statistics.html"><code class="docutils literal notranslate"><span class="pre">statistics</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="term_io.html"><code class="docutils literal notranslate"><span class="pre">term_io</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="timeout.html"><code class="docutils literal notranslate"><span class="pre">timeout</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="tsv.html"><code class="docutils literal notranslate"><span class="pre">tsv</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="types.html"><code class="docutils literal notranslate"><span class="pre">types</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="ulid.html"><code class="docutils literal notranslate"><span class="pre">ulid</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="unicode_data.html"><code class="docutils literal notranslate"><span class="pre">unicode_data</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="union_find.html"><code class="docutils literal notranslate"><span class="pre">union_find</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="uuid.html"><code class="docutils literal notranslate"><span class="pre">uuid</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="zippers.html"><code class="docutils literal notranslate"><span class="pre">zippers</span></code></a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../ports/index.html">Ports</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributions/index.html">Contributions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../bibliography.html">Bibliography</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>

    <p class="caption"><span class="caption-text">External Contents</span></p>
    <ul>
    <li class="toctree-l1"><a class="reference internal" href="../../apis/index.html">APIs</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://logtalk.org">Logtalk website</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://github.com/LogtalkDotOrg/logtalk3">GitHub repo</a></li>
    </ul>
  
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">The Logtalk Handbook</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">Libraries</a></li>
      <li class="breadcrumb-item active"><code class="docutils literal notranslate"><span class="pre">arbitrary</span></code></li>
      <li class="wy-breadcrumbs-aside">
              <a href="https://github.com/LogtalkDotOrg/logtalk3/blob/master/docs/handbook/sources/libraries/arbitrary.rst" class="fa fa-github"> Edit on GitHub</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="arbitrary">
<span id="library-arbitrary"></span><h1><code class="docutils literal notranslate"><span class="pre">arbitrary</span></code><a class="headerlink" href="#arbitrary" title="Link to this heading"></a></h1>
<p>The <code class="docutils literal notranslate"><span class="pre">arbitrary</span></code> library defines an <code class="docutils literal notranslate"><span class="pre">arbitrary</span></code> category providing
predicates for generating random values for selected types to the
<code class="docutils literal notranslate"><span class="pre">type</span></code> object, complementing its type checking predicates. Both the
object and the category predicates can be extended by the user with
definitions for new types by defining clauses for multifile predicates.
This library is notably used in the QuickCheck implementation by the
<code class="docutils literal notranslate"><span class="pre">lgtunit</span></code> tool. See also the documentation of the <code class="docutils literal notranslate"><span class="pre">mutations</span></code>
library for related functionality.</p>
<section id="api-documentation">
<h2>API documentation<a class="headerlink" href="#api-documentation" title="Link to this heading"></a></h2>
<p>Open the
<a class="reference external" href="../../apis/library_index.html#arbitrary">../../apis/library_index.html#arbitrary</a>
link in a web browser.</p>
</section>
<section id="loading">
<h2>Loading<a class="headerlink" href="#loading" title="Link to this heading"></a></h2>
<p>To load all entities in this library, load the <code class="docutils literal notranslate"><span class="pre">loader.lgt</span></code> file:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> <span class="k">logtalk_load</span>(arbitrary(loader)).
</pre></div>
</div>
</section>
<section id="testing">
<h2>Testing<a class="headerlink" href="#testing" title="Link to this heading"></a></h2>
<p>To test this library predicates, load the <code class="docutils literal notranslate"><span class="pre">tester.lgt</span></code> file:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> <span class="k">logtalk_load</span>(arbitrary(tester)).
</pre></div>
</div>
<p>Several of the provided tests are generic and verify the correct
behavior of all pre-defined and loaded user-defined generators and
shrinkers for all ground types.</p>
</section>
<section id="pre-defined-types">
<h2>Pre-defined types<a class="headerlink" href="#pre-defined-types" title="Link to this heading"></a></h2>
<p>This library defines random generators for the most common Logtalk and
Prolog types. See the <a class="reference external" href="../../apis/library_index.html#arbitrary">API
documentation</a> for a listing
of all the pre-defined types.</p>
</section>
<section id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Link to this heading"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">arbitrary</span></code> category complements the <code class="docutils literal notranslate"><span class="pre">type</span></code> object and thus its
predicates are accessed via this object. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> type<span class="o">::</span>arbitrary(integer, <span class="nv">Arbitrary</span>).
<span class="nv">Arbitrary</span> <span class="o">=</span> <span class="o">-</span><span class="m">816</span>
yes
</pre></div>
</div>
</section>
<section id="defining-new-generators-and-shrinkers">
<h2>Defining new generators and shrinkers<a class="headerlink" href="#defining-new-generators-and-shrinkers" title="Link to this heading"></a></h2>
<p>To define a generator of arbitrary values for a type, define a clause
for the <code class="docutils literal notranslate"><span class="pre">arbitrary::arbitrary/1</span></code> multifile predicate specifying the
type and a clause for the <code class="docutils literal notranslate"><span class="pre">arbitrary::arbitrary/2</span></code> multifile predicate
generating an arbitrary term of the specified type. As a simple example,
assume that we want to define an “odd integer type”. We start by
defining both the type checker and the arbitrary generator:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">multifile</span>(type<span class="o">::</span>type<span class="o">/</span><span class="m">1</span>).
type<span class="o">::</span>type(odd).

<span class="p">:- </span><span class="k">multifile</span>(type<span class="o">::</span>check<span class="o">/</span><span class="m">2</span>).
type<span class="o">::</span>check(odd, <span class="nv">Term</span>) <span class="o">:-</span>
    (   <span class="k">var</span>(<span class="nv">Term</span>) <span class="o">-&gt;</span>
        <span class="k">throw</span>(<span class="k">instantiation_error</span>)
    <span class="o">;</span>   <span class="k">integer</span>(<span class="nv">Term</span>),
        <span class="nv">Term</span> <span class="o">mod</span> <span class="m">2</span> <span class="o">=:=</span> <span class="m">1</span> <span class="o">-&gt;</span>
        <span class="k">true</span>
    <span class="o">;</span>   <span class="k">throw</span>(<span class="k">type_error</span>(odd, <span class="nv">Term</span>))
    ).

<span class="p">:- </span><span class="k">multifile</span>(arbitrary<span class="o">::</span>arbitrary<span class="o">/</span><span class="m">1</span>).
arbitrary<span class="o">::</span>arbitrary(odd).

<span class="p">:- </span><span class="k">multifile</span>(arbitrary<span class="o">::</span>arbitrary<span class="o">/</span><span class="m">2</span>).
arbitrary<span class="o">::</span>arbitrary(odd, <span class="nv">Arbitrary</span>) <span class="o">:-</span>
    type<span class="o">::</span>arbitrary(integer, <span class="nv">Arbitrary0</span>),
    (   <span class="nv">Arbitrary0</span> <span class="o">mod</span> <span class="m">2</span> <span class="o">=:=</span> <span class="m">1</span> <span class="o">-&gt;</span>
        <span class="nv">Arbitrary</span> <span class="o">=</span> <span class="nv">Arbitrary0</span>
    <span class="o">;</span>   <span class="nv">Arbitrary</span> <span class="k">is</span> <span class="nv">Arbitrary0</span> <span class="o">+</span> <span class="m">1</span>
    ).
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">arbitrary</span></code> library also provides <em>meta-types</em> that can simplify
the definition of new generators. For example, the <code class="docutils literal notranslate"><span class="pre">odd</span></code> type above
can also be defined using the <code class="docutils literal notranslate"><span class="pre">constrain/2</span></code> meta-type to only generate
values that satisfy a closure:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>arbitrary<span class="o">::</span>arbitrary(odd, <span class="nv">Arbitrary</span>) <span class="o">:-</span>
    arbitrary(constrain(integer, [<span class="nv">Arbitrary</span>]<span class="o">&gt;&gt;</span>(<span class="nv">Arbitrary</span> <span class="o">mod</span> <span class="m">2</span> <span class="o">=:=</span> <span class="m">1</span>)), <span class="nv">Arbitrary</span>).
</pre></div>
</div>
<p>Another example is using the <code class="docutils literal notranslate"><span class="pre">transform/2</span></code> meta-type to transform
generated values for a base type using a closure. Assuming that we want
to generate a sorted list of random integers, we can write:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>arbitrary<span class="o">::</span>arbitrary(sorted_integer_list, <span class="nv">Arbitrary</span>) <span class="o">:-</span>
    arbitrary(transform(list(integer), sort), <span class="nv">Arbitrary</span>).
</pre></div>
</div>
<p>We can also define a clause for the <code class="docutils literal notranslate"><span class="pre">arbitrary::shrinker/1</span></code> multifile
predicate to declare a new shrinker and a <code class="docutils literal notranslate"><span class="pre">arbitrary::shrink/3</span></code>
multifile predicate for shrinking arbitrary values for QuickCheck usage:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">multifile</span>(arbitrary<span class="o">::</span>shrinker<span class="o">/</span><span class="m">1</span>).
arbitrary<span class="o">::</span>shrinker(odd).

<span class="p">:- </span><span class="k">multifile</span>(arbitrary<span class="o">::</span>shrink<span class="o">/</span><span class="m">3</span>).
arbitrary<span class="o">::</span>shrink(odd, <span class="nv">Large</span>, <span class="nv">Small</span>) <span class="o">:-</span>
    <span class="k">integer</span>(<span class="nv">Large</span>),
    (   <span class="nv">Large</span> <span class="o">&lt;</span> <span class="o">-</span><span class="m">1</span> <span class="o">-&gt;</span>
        <span class="nv">Small</span> <span class="k">is</span> <span class="nv">Large</span> <span class="o">+</span> <span class="m">2</span>
    <span class="o">;</span>   <span class="nv">Large</span> <span class="o">&gt;</span> <span class="m">1</span>,
        <span class="nv">Small</span> <span class="k">is</span> <span class="nv">Large</span> <span class="o">-</span> <span class="m">2</span>
    ).
</pre></div>
</div>
<p>Definitions for the <code class="docutils literal notranslate"><span class="pre">shrink/3</span></code> predicate should either succeed or fail
but never throw an exception. The <code class="docutils literal notranslate"><span class="pre">shrink_sequence/3</span></code> predicate can be
used to help test that shrinking a value results in a finite sequence of
values.</p>
<p>It is also possible to define edge cases for a given type for use with
QuickCheck implementations. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">multifile</span>(arbitrary<span class="o">::</span>edge_case<span class="o">/</span><span class="m">2</span>).
arbitrary<span class="o">::</span>edge_case(odd,  <span class="m">1</span>).
arbitrary<span class="o">::</span>edge_case(odd, <span class="o">-</span><span class="m">1</span>).
</pre></div>
</div>
<p>Edge cases are tried before resorting to generating arbitrary values for
a type.</p>
<p>A more complex example is generating arbitrary values for a recursive
type. A simple example of a recursive type is a binary tree. Assuming
that we are working with a binary tree holding integers where each node
is represented by a <code class="docutils literal notranslate"><span class="pre">node(Left,</span> <span class="pre">Right)</span></code> compound term, we can define a
<code class="docutils literal notranslate"><span class="pre">node(Depth)</span></code> type where <code class="docutils literal notranslate"><span class="pre">Depth</span></code> is the maximum depth of the tree.
This argument allows us to prevent excessively deep trees:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">category</span>(binary_tree).

<span class="p">    :- </span><span class="k">multifile</span>(type<span class="o">::</span>type<span class="o">/</span><span class="m">1</span>).
    type<span class="o">::</span>type(node(<span class="nv">_</span>)).

<span class="p">    :- </span><span class="k">multifile</span>(type<span class="o">::</span>check<span class="o">/</span><span class="m">2</span>).
    type<span class="o">::</span>check(node(<span class="nv">_</span>), <span class="nv">Term</span>) <span class="o">:-</span>
        (   check(<span class="nv">Term</span>) <span class="o">-&gt;</span>
            <span class="k">true</span>
        <span class="o">;</span>   <span class="k">var</span>(<span class="nv">Term</span>) <span class="o">-&gt;</span>
            <span class="k">throw</span>(<span class="k">instantiation_error</span>)
        <span class="o">;</span>   <span class="k">throw</span>(<span class="k">type_error</span>(node(<span class="nv">_</span>), <span class="nv">Term</span>))
        ).

    check(<span class="nv">Term</span>) <span class="o">:-</span>
        (   <span class="k">integer</span>(<span class="nv">Term</span>) <span class="o">-&gt;</span>
            <span class="k">true</span>
        <span class="o">;</span>   <span class="k">compound</span>(<span class="nv">Term</span>),
            <span class="nv">Term</span> <span class="o">=</span> node(<span class="nv">Left</span>, <span class="nv">Right</span>),
            check(<span class="nv">Left</span>),
            check(<span class="nv">Right</span>)
        ).

<span class="p">    :- </span><span class="k">multifile</span>(arbitrary<span class="o">::</span>arbitrary<span class="o">/</span><span class="m">1</span>).
    arbitrary<span class="o">::</span>arbitrary(node(<span class="nv">_</span>)).

<span class="p">    :- </span><span class="k">multifile</span>(arbitrary<span class="o">::</span>arbitrary<span class="o">/</span><span class="m">2</span>).
    arbitrary<span class="o">::</span>arbitrary(node(<span class="nv">Depth</span>), <span class="nv">Arbitrary</span>) <span class="o">:-</span>
    (   <span class="nv">Depth</span> <span class="o">&gt;</span> <span class="m">1</span> <span class="o">-&gt;</span>
        <span class="nv">NewDepth</span> <span class="k">is</span> <span class="nv">Depth</span> <span class="o">-</span> <span class="m">1</span>,
        type<span class="o">::</span>arbitrary(
            types_frequency([
                integer <span class="o">-</span> <span class="m">1</span>,
                <span class="k">compound</span>(
                    node,
                    [
                        types([node(<span class="nv">NewDepth</span>), integer]),
                        types([node(<span class="nv">NewDepth</span>), integer])
                    ]
                ) <span class="o">-</span> <span class="m">3</span>
            ]),
            <span class="nv">Arbitrary</span>
        )
    <span class="o">;</span>   type<span class="o">::</span>arbitrary(
    integer, <span class="nv">Arbitrary</span>)
    ).

<span class="p">:- </span><span class="k">end_category</span>.
</pre></div>
</div>
<p>In this second example, we use some of the pre-defined types provided by
the library. The <code class="docutils literal notranslate"><span class="pre">types_frequency(Pairs)</span></code> type supports generating
random terms for a type in the <code class="docutils literal notranslate"><span class="pre">Type-Frequency</span></code> pairs list where the
type is randomly chosen after the types relative frequency. The
<code class="docutils literal notranslate"><span class="pre">compound(Name,</span> <span class="pre">Types)</span></code> type supports generating compound terms with a
given name and random arguments after the given types:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> type<span class="o">::</span>arbitrary(node(<span class="m">4</span>), <span class="nv">Arbitrary</span>).
<span class="nv">Arbitrary</span> <span class="o">=</span> <span class="m">907</span>
yes

| <span class="o">?-</span> type<span class="o">::</span>arbitrary(node(<span class="m">4</span>), <span class="nv">Arbitrary</span>).
<span class="nv">Arbitrary</span> <span class="o">=</span> node(node(node(<span class="m">522</span>, <span class="m">509</span>), node(<span class="m">83</span>, <span class="m">453</span>)), node(<span class="m">454</span>, <span class="o">-</span><span class="m">197</span>))
yes

| <span class="o">?-</span> type<span class="o">::</span>arbitrary(node(<span class="m">4</span>), <span class="nv">Arbitrary</span>).
<span class="nv">Arbitrary</span> <span class="o">=</span> node(node(<span class="o">-</span><span class="m">875</span>, <span class="o">-</span><span class="m">866</span>), <span class="o">-</span><span class="m">254</span>)
yes

| <span class="o">?-</span> type<span class="o">::</span>arbitrary(node(<span class="m">4</span>), <span class="nv">Arbitrary</span>).
<span class="nv">Arbitrary</span> <span class="o">=</span> node(<span class="o">-</span><span class="m">133</span>, <span class="o">-</span><span class="m">831</span>)
yes
</pre></div>
</div>
<p>The source code of these examples can be found in the <code class="docutils literal notranslate"><span class="pre">test_files</span></code>
directory. Other examples of arbitrary term generators can be found in
the implementation of the <code class="docutils literal notranslate"><span class="pre">optionals</span></code> and <code class="docutils literal notranslate"><span class="pre">expecteds</span></code> libraries.</p>
</section>
<section id="scoped-generators-and-shrinkers">
<h2>Scoped generators and shrinkers<a class="headerlink" href="#scoped-generators-and-shrinkers" title="Link to this heading"></a></h2>
<p>Declaring a new generator and possibly a shrinker for a custom type
raises the possibility of a conflict with third-party-defined generators
and shrinkers. An alternative is to use the <code class="docutils literal notranslate"><span class="pre">(::)/2</span></code> meta-type to
define scoped generators and shrinkers. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(scoped).

    <span class="c">% the same predicate is used for both generating and validating</span>
<span class="p">    :- </span><span class="k">public</span>(custom<span class="o">/</span><span class="m">1</span>).
    custom(<span class="nv">Term</span>) <span class="o">:-</span>
        (   <span class="k">var</span>(<span class="nv">Term</span>) <span class="o">-&gt;</span>
            <span class="c">% assume predicate used as a generator</span>
            random<span class="o">::</span>random(<span class="nv">Term</span>)
        <span class="o">;</span>   <span class="c">% assume predicate used as a validator</span>
            <span class="k">float</span>(<span class="nv">Term</span>)
        ).

    <span class="c">% a predicate with the same name is used for shrinking</span>
<span class="p">    :- </span><span class="k">public</span>(custom<span class="o">/</span><span class="m">2</span>).
    custom(<span class="nv">Larger</span>, <span class="nv">Small</span>) <span class="o">:-</span>
        <span class="nv">Small</span> <span class="k">is</span> <span class="nv">Larger</span> <span class="o">/</span> <span class="m">2.</span>

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Some sample calls:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> type<span class="o">::</span>arbitrary(scoped<span class="o">::</span>custom, <span class="nv">Arbitrary</span>).
<span class="nv">Arbitrary</span> <span class="o">=</span> <span class="m">0.5788130906607927</span>
yes

| <span class="o">?-</span> type<span class="o">::</span>valid(scoped<span class="o">::</span>custom, foo).
no

| <span class="o">?-</span> type<span class="o">::</span>check(scoped<span class="o">::</span>custom, <span class="nv">_</span>).
<span class="nv">ERROR</span><span class="o">:</span> <span class="k">type_error</span>(<span class="k">instantiation_error</span>)

| <span class="o">?-</span> type<span class="o">::</span>check(scoped<span class="o">::</span>custom, foo).
<span class="nv">ERROR</span><span class="o">:</span> <span class="k">type_error</span>(scoped<span class="o">::</span>custom, foo)

| <span class="o">?-</span> type<span class="o">::</span>shrink(scoped<span class="o">::</span>custom, <span class="m">0.42</span>, <span class="nv">Smaller</span>).
<span class="nv">Smaller</span> <span class="o">=</span> <span class="m">0.21</span>
yes
</pre></div>
</div>
<p>The source code of this example can be found in the <code class="docutils literal notranslate"><span class="pre">test_files</span></code>
directory.</p>
</section>
<section id="reproducing-sequences-of-arbitrary-terms">
<h2>Reproducing sequences of arbitrary terms<a class="headerlink" href="#reproducing-sequences-of-arbitrary-terms" title="Link to this heading"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">arbitrary</span></code> category provides access to the pseudo-random
generator it uses via the <code class="docutils literal notranslate"><span class="pre">get_seed/1</span></code> and <code class="docutils literal notranslate"><span class="pre">set_seed/1</span></code>. This allows
sequences of arbitrary values to be reproduced. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> type<span class="o">::</span>get_seed(<span class="nv">Seed</span>).
<span class="nv">Seed</span> <span class="o">=</span> seed(<span class="m">3172</span>, <span class="m">9814</span>, <span class="m">20125</span>)
yes

| <span class="o">?-</span> type<span class="o">::</span>arbitrary(integer, <span class="nv">Arbitrary</span>).
<span class="nv">Arbitrary</span> <span class="o">=</span> <span class="o">-</span><span class="m">816</span>
yes

| <span class="o">?-</span> type<span class="o">::</span>arbitrary(integer, <span class="nv">Arbitrary</span>).
<span class="nv">Arbitrary</span> <span class="o">=</span> <span class="o">-</span><span class="m">113</span>
yes

| <span class="o">?-</span> type<span class="o">::</span>arbitrary(integer, <span class="nv">Arbitrary</span>).
<span class="nv">Arbitrary</span> <span class="o">=</span> <span class="m">446</span>

| <span class="o">?-</span> type<span class="o">::</span>set_seed(seed(<span class="m">3172</span>, <span class="m">9814</span>, <span class="m">20125</span>)).
yes

| <span class="o">?-</span> type<span class="o">::</span>arbitrary(integer, <span class="nv">Arbitrary</span>).
<span class="nv">Arbitrary</span> <span class="o">=</span> <span class="o">-</span><span class="m">816</span>
yes

| <span class="o">?-</span> type<span class="o">::</span>arbitrary(integer, <span class="nv">Arbitrary</span>).
<span class="nv">Arbitrary</span> <span class="o">=</span> <span class="o">-</span><span class="m">113</span>
yes

| <span class="o">?-</span> type<span class="o">::</span>arbitrary(integer, <span class="nv">Arbitrary</span>).
<span class="nv">Arbitrary</span> <span class="o">=</span> <span class="m">446</span>
yes
</pre></div>
</div>
<p>The seed should be regarded as an opaque term and handled using the
<code class="docutils literal notranslate"><span class="pre">get_seed/1</span></code> and <code class="docutils literal notranslate"><span class="pre">set_seed/1</span></code> predicates. These predicates are
notably used in the QuickCheck implementation provided by the
<code class="docutils literal notranslate"><span class="pre">lgtunit</span></code> tool.</p>
</section>
<section id="default-size-of-generated-terms">
<h2>Default size of generated terms<a class="headerlink" href="#default-size-of-generated-terms" title="Link to this heading"></a></h2>
<p>The library uses the value 42 for the default size of generated terms
for types where size is meaningful and implicit. To override this
default value, define a clause for the <code class="docutils literal notranslate"><span class="pre">arbitrary::max_size/1</span></code>
multifile predicate. The new default size must be a positive integer.
For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">multifile</span>(arbitrary<span class="o">::</span>max_size<span class="o">/</span><span class="m">1</span>).
arbitrary<span class="o">::</span>max_size(<span class="m">7</span>).
</pre></div>
</div>
<p>When multiple definitions exist, the first valid one found is used. When
no definition is valid, the default value of 42 is used.</p>
</section>
<section id="known-issues">
<h2>Known issues<a class="headerlink" href="#known-issues" title="Link to this heading"></a></h2>
<p>Some Prolog systems either don’t support the null character or provide
buggy results when calling <code class="docutils literal notranslate"><span class="pre">char_code/2</span></code> with a code of zero. When
that’s the case, the null character is excluded when generating
arbitrary characters or character codes.</p>
<p>Generating arbitrary Unicode characters (instead of Unicode codepoints)
is inherently problematic as the process first generates codepoints and
then tries to use the standard <code class="docutils literal notranslate"><span class="pre">char_code/2</span></code> to convert them to
characters. But, depending on the backend Prolog system and its internal
(if any) Unicode normalization, it may not be possible to convert a
codepoint to a single character.</p>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="overview.html" class="btn btn-neutral float-left" title="Overview" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="assignvars.html" class="btn btn-neutral float-right" title="assignvars" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 1998-2025, Paulo Moura.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>